¬  Packager.app v1.1

Written and maintained by Toby Paterson
E-Mail:	tpaterso@cs.ubc.ca or paterson@gdss.commerce.ubc.ca
Land Mail:	2905 Marine Drive,
	West Vancouver, BC
	Canada  V7V 1M2

An Installer package is a convenient means for packaging a complex software system for distribution.  When NeXT provided us with Installer.app, they gave us a great way to automagically install pre-packaged software such as Mathematica, X windows, etc.  Packager.app is an application designed to run in conjunction with Next's Installer.app.  It provides a drag-n-drop environment for building Installer packages and it overcomes several limitations of the conventional tools used for building packages.  This documentation assumes that the reader is familiar with the NextStep environment and acquainted with Installer.app.  Installer.app is completely documented in the Digital Librarian.

Building Packages

Adding files to a package is as simple as selecting the files from the Workspace manager and dragging them in to the Package window (see figure 1).  Alternatively, you may select the Add Contents... item from the Package menu which will pop up the standard file browser panel.  The contents of a package are displayed in a browser in the Package window;  the icon to the left of the file name indicates what type of file it is.  Currently, only three categories of files are recognized:

¬	applications and executables
¬	folders
¬	all other kinds of files

To remove files from a package, select the files-non-grata in the contents browser and press the delete key.  The contents of a package may also be perused using the arrow keys in the browser.

¬
Figure 1.  Package window

Important:  the contents of a package are shown in the contents browser using their full path name.  When the package is built, however, the longest path common to all files is removed from their name.  Thus the contents of the package in figure 1 would have /Users/paterson/ stripped from their name and would be archived in the package as

./Apps/Packager.app
./Packager
./tmp/packager build_menu.tiff
./tmp/packager main_menu.tiff
./tmp/packager info_menu.tiff

When the package is installed, these files would be stored relative to the installation location.  Any directory names in the file path are created as needed automatically.  For example, if you told Installer.app to install the package in the directory /LocalApps, the files would be unpackaged as

/LocalApps/Apps/Packager.app
/LocalApps/Packager
/LocalApps/tmp/packager build_menu.tiff
/LocalApps/tmp/packager main_menu.tiff
/LocalApps/tmp/packager info_menu.tiff

Before the package can be built, it must be given a title.  You may also change the other information from the supplied defaults.  The fields have the following meanings (more or less gutted and pasted from the Digital Librarian docs on Installer):

Title	The title will be displayed at the top of the Info view in the Installer's Package window when the package is opened.  By default, it is also the name used for the package with a .pkg extension tacked on the end.  It should be less than 50 characters or so and may contain any characters.

Icon	The icon will be shown next to the title in the Info view in Installer's Package window.  It must be a 48x48 pixel TIFF image although it may be any depth (that is, colour, grey scale or black and white).  You may change the icon by dragging a TIFF image from the Workspace into the icon well (see figure 1).

Version	The value of this field will be displayed in the Version field of the Info view.  The value should be something like ª23º or ª56.3aº or ªv7.0, Jun 24 1990 14:35º.

Description	The value of this field will be displayed in the Description field of the Info view.  The description should be a brief message that will tell the customer about the contents of the package.  The value of this field can be at most 1023 characters in length.

Default Location	The value of this field determines where the contents of the package will be installed.  The value should be a UNIX pathname, preferably ~/Apps (or possibly /LocalApps).  If the Relocatable switch is not set, then this value will be used without modification as the root directory relative to which the contents of the package are installed.  On the other hand, if the Relocatable switch is set, then the Default Location is used as the initial directory for the InstallIn panel, from which the user chooses a destination root directory for the installation.

	Restriction:  The value of the Default Location must not contain whitespace (such as blanks and tabs) or the following shell metacharacters:

		!  $  ^  &  *  (  )  {  }  [  ]  \  |  ;  <  >  ?  '  "  `

Disk Name	The  Installer uses this value to compute the disk name when prompting the user to insert a floppy or optical disk.  When the entire package fits on a single disk (that is, when it's a single-volume package), the value of this field should be exactly equal to the disk label.  For example, if the Foo package fits onto a single floppy and the floppy disk is mounted with the name ªFoo Softwareº when the disk is inserted, then the Disk Name should be

		Foo Software

	When the package is to be distributed on more than one floppy, the value of this field should contain a single instance of the substring ª%dº.  This value will be used as a pattern, with the substring "%d" successively replaced by the numbers 1, 2, 3, ..., etc.  For example, if the Foo package is distributed on floppies labeled "Foo Software #1", "Foo Software #2", ..., "Foo Software #n", then Disk Name should be

		Foo Software #%d
	
	There should be no other occurrences of the % character in this field.

	Restriction:  The Disk Name must not contain the following shell metacharacters:

		!  $  ^  &  *  (  )  {  }  [  ]  \  |  ;  <  >  ?  '  "  `

Delete Warning	The value of this field will be displayed as the contents of an Alert panel that prompts for confirmation when the user attempts to delete the package from Installer.  The warning should be short, preferably a single sentence, and it should be used when the developer wants to inform the customer of any dangers or side effects of deleting the package.

The relocatable switch determines whether or not the installation directory of your package is fixed (see Default Location above) and the Application switch should be set if your package contains an application.

If you are distributing your system on floppy disks and the package is too large to fit on one disk, you can break it up into chunks, each of which can fit onto a single disk.  Installer can then assemble these chunks from the floppy disk back into the complete package when installing it.  Or so they tell me; I've never actually tried it out.  To chunk a package in this manner, switch to the Chunks view in the Package window (using the popup menu in the Package window) and select the size of your disk.  Packager will automatically break up your package into chunks of the appropriate size.

¬
Figure 2.  The Package window popup menu

When your package is ready to be built, select the Build item from the Package menu.  The Package window will automatically change to the Progress view which monitors the progress of the build.  A complete transaction of the build is maintained in the Log view and any errors are reported here in detail.

Packager Menus

¬

Info Panel...	No prizes for guessing this one.

Comments...	Pop up a window which can be used to automatically mail any feedback you have directly to me, the author.  I welcome any comments you have (as long as they are nice) and dread any bug reports.

¬

Open	Open an existing package and modify it.  This option is not yet implemented.

New	Create a new package.  The contents of the current package (if any) are emptied and the package information fields are reset to their default values.

Build	Build a new package.  A window will popup asking for a location and name for the new package.

Add Contents...	Add files to the current package using the standard file browser panel.  For the pedantic ones amongst us.

Bugs and Stuff That It Would Be Really Nice To Have

·	The Information view is somewhat vestigal right now.  I put it in mostly to remind me to implement it some day.  Soon.

·	It is not possible to open an existing package and modify it.  Thus a package has to be built from scratch everytime it needs to be changed.  Another useful feature would be the ability to save the contents/information of a package without having to actually build the package.

·	The contents browser should show the file names with the longest common path removed, not the full pathname.